# Admin Documentation: Permissions & Subscriptions This document provides an overview and guide for administrators to manage user permissions and the subscription system within the application. ## Part 1: Permissions Management The application employs a multi-layered permissions system to control user access to various functionalities and modules. ### 1.1. Overview of Roles & Permissions * **Simple Role (`users` table `role` column):** * A basic role assignment directly on the user model. * Values: `user`, `admin`, `super_admin`. * `super_admin`: Has unrestricted access to all system functionalities, including managing other administrators and critical settings. * `admin`: Has access to the admin panel, but their specific capabilities can be further refined by module permissions and Spatie roles. * `user`: Standard user with access to frontend features based on their subscriptions and other permissions. * **Spatie Roles & Permissions (Advanced):** * The application uses the `spatie/laravel-permission` package for more granular permission control. * **Roles:** Definable roles (e.g., "Company Owner", "Job Seeker", "Editor") that can be assigned to users. These are managed via `Admin Panel -> Roles`. * **Permissions:** Specific actions (e.g., "edit articles", "manage_company_profile"). These are typically defined in code and seeded. * Users can have multiple Spatie roles. * **Module Permissions (`module_permissions` table):** * Controls which **Spatie roles** have access to entire **modules**. * This acts as a top-level gate for module access. If a role doesn't have permission for a module here, users with that role won't access any part of it, regardless of feature-specific settings. * Currently, this is primarily managed for the `admin` (Spatie) role via the "Edit User" page in the admin panel (the section "Admin Role Module Access"). * **Feature Role Access (`feature_role_access` table):** * Provides the most granular control. * Defines how specific **Spatie roles** interact with individual **features** (defined in `module.json` files). * Access types: * `free`: The feature is free for this role (may still have credit costs). * `paid`: The feature requires a subscription for this role. * `denied`: The feature is explicitly denied for this role, overriding all other settings. * Can also specify `credit_cost` and `default_limit` per feature per role. * This is typically managed directly in the database or via a future dedicated admin interface. ### 1.2. Managing Users & Roles * **Creating/Editing Users (Admin Panel -> Users):** * **Name, Email, Password:** Standard user fields. * **Simple Role:** * Super Admins can assign `user`, `admin`, or `super_admin`. * Regular Admins typically cannot change this field for other users, especially not to `super_admin`. * **Spatie Roles:** * Super Admins can assign any Spatie roles to users. * Select roles from the "Spatie Roles" multi-select field. * If Spatie teams are enabled (`config/permission.php` `teams` => `true`), roles are assigned within the user's current team context. * **Important Notes:** * There should always be at least one `super_admin`. The system prevents the last Super Admin from being demoted or deleted. * Regular `admin` users cannot modify `super_admin` accounts. ### 1.3. Managing Module Access for the 'admin' Role Super Admins can control which modules are accessible to users who have the **Spatie role** named `admin`. * **Location:** `Admin Panel -> Users -> Edit User` (select any user, the relevant section is "Admin Role Module Access"). * *Rationale: This section modifies permissions for the 'admin' role itself, not the specific user being edited. This UI might be consolidated into a dedicated "Role Management" section in the future.* * **Functionality:** * A list of all enabled modules is displayed. * Check the boxes next to modules that the `admin` (Spatie) role should have access to. * Unchecking a box revokes access for the `admin` role to that module. * This updates the `module_permissions` table for the `role_name` = `admin`. ### 1.4. Feature Configuration in `module.json` Each module's `module.json` file plays a critical role in defining features and how they interact with the permission and subscription systems. * **`features` array:** * `key`: Unique identifier for the feature (e.g., `businessdirectory_post_jobs`). This key is used in subscription plans and `feature_role_access`. * `name`: User-friendly name of the feature. * `description`: Explanation of the feature. * `requires_subscription` (boolean): * `true`: The feature generally requires an active subscription (unless overridden by `feature_role_access` to be `free` or `denied` for a specific role). * `false`: The feature is generally free (unless overridden by `feature_role_access` to be `paid` or `denied`). * `limitable` (boolean): If `true`, this feature's usage can be limited by subscription plans (e.g., "Max Job Posts"). * `limit_label`: User-friendly label for the limit (e.g., "Max Job Posts per Month"). * `credit_cost` (integer, optional): Default credit cost for using this feature if not overridden by `feature_role_access` or `feature_credit_costs` table. * `target_role_hint` (string, optional): A hint for admins about which user role this feature is typically intended for (e.g., "company_owner", "job_seeker"). * `user_route_name` (string, optional): The route name for users to access/initiate this feature (used by some system components). * **`user_menu` array:** Defines items that appear in the user's sidebar. * `title`: Text of the menu link. * `route_name`: The Laravel named route for the link. * `icon_svg_path`: SVG path data for the icon. * `associated_feature_key` (optional): If present, the link will only show if the user has access to this feature (checked via `SidebarAccessHelper` which uses `UserAccessHelper`). If absent, the link is considered general and will show if the route exists and the module is enabled. * **`requires_subscription` (module-level boolean):** * `true`: The entire module generally requires a subscription to access its features. Individual features within can still be marked as `requires_subscription: false` to be free, but access to the module itself is gated. * `false`: The module itself is considered free. Access to its features will depend on their individual `requires_subscription` flags and `feature_role_access` rules. ### 1.5. Best Practices for Permissions * **Principle of Least Privilege:** Grant users and roles only the permissions necessary to perform their tasks. * **Regular Review:** Periodically review user roles and permissions to ensure they are still appropriate. * **Super Admin Care:** Limit the number of Super Admins and ensure their credentials are secure. ## Part 2: Subscription System Management The subscription system controls user access to premium features and modules based on purchased or assigned plans. ### 2.1. Overview * **Purpose:** Monetize features, offer tiered access, and manage user entitlements. * **Key Components:** * **Subscription Plans:** Define the offerings (price, duration, features, limits). * **Subscriptions:** Link a user to a specific plan for a defined period. * **Features:** Granular functionalities defined in `module.json` files, which are then included in plans. ### 2.2. Enabling/Disabling the Subscription System * **Global Setting:** `subscriptions_enabled` * **Location:** `Admin Panel -> Settings -> Subscriptions (tab)` * If **disabled** (`0`): * Most `requires_subscription: true` checks in `UserAccessHelper` are bypassed, effectively making many premium features accessible. * Role-based denials (`feature_role_access` set to `denied`) and module permission restrictions will still apply. * The "Subscription Plans" link will not appear in the user sidebar. * If **enabled** (`1`): * The system enforces subscription checks as defined. ### 2.3. Managing Subscription Plans * **Location:** `Admin Panel -> Subscription Plans` * **Creating a New Plan:** * **Name & Description:** User-friendly details for the plan. * **Price & Currency:** Cost of the plan. * **Interval & Interval Count:** Billing cycle (e.g., `month` with count `1` for monthly, `year` with count `1` for yearly). * **Trial Period Days:** Number of days for a free trial (optional). * **Active:** Check to make the plan available for users to subscribe to. * **Target Role:** * `General (All Users)`: Plan is available to any user. * Specific Spatie Role (e.g., `company_owner`): Plan is only visible/assignable to users with this Spatie role. This allows for role-specific pricing or feature bundles. * **Features:** * Select features to include in this plan from the list of all available features (collated from all enabled modules' `module.json` files). * For each selected `limitable` feature, set a **Limit** (e.g., number of job posts). Enter `0` for unlimited access to that feature within the plan. * **Resource Limits (Global):** Define plan-wide limits not tied to specific module features (e.g., "Max Storage: 500 MB"). These are defined as key-value pairs. * **Available Payment Gateways:** Select which payment gateways can be used to purchase this plan. * **Credits Awarded on Purchase:** Number of credits automatically awarded to the user when they first subscribe to this plan. * **Credits Awarded on Renewal:** Number of credits awarded on subsequent successful renewals. * **Editing Existing Plans:** Modify any of the above details. Changes may affect future subscriptions or renewals, depending on your gateway and renewal logic. * **Deleting Plans:** * Removes the plan from the system. * **Caution:** Deleting a plan does *not* automatically cancel active subscriptions of users on that plan. Their current subscription period will continue. You may need to manually manage users on deleted plans or implement logic for migration. ### 2.4. Managing User Subscriptions * **Location:** `Admin Panel -> Users -> Edit User -> Subscription (tab)` * **Assigning/Changing a Plan:** * Super Admins can select a plan from the "Assign New Subscription Plan" dropdown and click "Assign Plan". * This will cancel any existing active/trialing subscription for the user and create a new one for the selected plan. The payment gateway will be marked as `admin_assigned`. * **Removing/Cancelling a Subscription:** * Click the "Cancel Current Subscription" button. * This sets the user's current active/trialing subscription status to `cancelled` and sets `ends_at` to the current time. * **Viewing Current Subscription:** Details of the user's active/trialing subscription (if any) are displayed. ### 2.5. Payment Gateways * **General Configuration:** `Admin Panel -> Settings -> Payment Gateways (tab)` (or similar, depending on your settings structure). This is where you'd set global gateway settings if any. * **Module-based Gateways (e.g., Stripe, PayPal, Authorize.Net, Paystack):** * **Enable Module:** `Admin Panel -> Modules`. The gateway module must be enabled. * **Enable Gateway Setting:** Each gateway module typically has its own "Enable [Gateway Name]" setting (e.g., `stripe_enabled`, `paypal_enabled`) in `Admin Panel -> Settings -> [Module Name] (tab)` or `Admin Panel -> Settings -> Payment Gateways (tab)`. * **API Credentials:** Configure API keys, secrets, public keys, etc., in the respective module's settings page or the main Payment Gateways settings tab. * **Custom Payment Gateway:** * **Enable Setting:** `custom_payment_gateway_enabled` in `Admin Panel -> Settings`. * **Name Setting:** `custom_payment_gateway_name` (e.g., "Bank Transfer Instructions"). * **Instructions:** `custom_payment_gateway_instructions` (HTML allowed). * When a user selects this, they see the instructions. Admins then manually verify payment and activate the subscription. * **Wallet System as Payment Method:** * **Enable Setting:** `wallet_system_enabled` in `Admin Panel -> Settings`. * If enabled and selected as an "Available Gateway" for a plan, users can pay using their wallet balance. ### 2.6. Credit System Integration with Subscriptions * **Global Setting:** `credits_system_enabled` in `Admin Panel -> Settings`. * **Plan-based Credit Awards:** * `credits_awarded_on_purchase`: Set per plan. Awarded when a subscription to that plan starts. * `credits_awarded_on_renewal`: Set per plan. Awarded when a subscription to that plan successfully renews. * **Feature Credit Costs:** * Defined in the `feature_credit_costs` table (for overrides) or as `credit_cost` in a feature's definition in `module.json`. * `UserAccessHelper` checks if a user has enough credits if a feature costs credits, even if it's "free" by subscription or role. ### 2.7. Troubleshooting Common Subscription Issues * **User cannot see a plan:** * Check if the plan is "Active". * Check the plan's "Target Role" against the user's Spatie roles. * Ensure the global `subscriptions_enabled` setting is on. * **User cannot access a feature they should have:** * Verify their subscription is active and for the correct plan. * Check the plan's "Features" list to ensure the feature is included and the limit is not exceeded (if applicable). * Check `feature_role_access` for any "denied" rules for the user's Spatie role(s). * Check `module_permissions` if the feature belongs to a module that the user's role might not have access to. * Check if the feature requires credits and if the user has sufficient balance. * **Payment Gateway Not Appearing:** * Ensure the gateway module is enabled. * Ensure the gateway's specific "enable" setting is on. * Ensure API credentials for the gateway are correctly configured. * Ensure the gateway is selected in the "Available Payment Gateways" for the specific subscription plan. --- This documentation should serve as a good starting point for administrators. It can be expanded with more specific examples or screenshots as needed.